프로젝트의 프론트엔드 리포지토리입니다.
| Category | Technology |
|---|---|
| Framework | Next.js 16 (App Router), React 19 |
| Language | TypeScript 5 |
| Auth | Supabase Auth (@supabase/ssr) |
| State Management | Zustand |
| Styling | Tailwind CSS 4, Radix UI, Lucide React |
| API & Data | Axios, Orval (API Code Generation), Zod |
| PWA | @ducanh2912/next-pwa |
| Animation | Framer Motion |
| Documentation | Storybook |
| Testing | Jest, React Testing Library, Playwright (E2E) |
| Package Manager | pnpm |
| Linting & Formatting | ESLint, Prettier, Stylelint, Husky, Commitlint |
├── app/ # Next.js App Router (Pages, API, Layouts)
│ ├── (auth)/ # 인증 관련 페이지 (Login, Callback 등)
│ ├── (main)/ # 메인 서비스 페이지 (Home, Bookmark, MyPage 등)
│ ├── api/ # API Route Handlers (Geocode 등)
│ ├── globals.css # Global Styles
│ └── layout.tsx # Root Layout
├── components/ # 재사용 가능한 UI 컴포넌트
│ ├── common/ # 공통 컴포넌트 (SplashScreen 등)
│ ├── home/ # 홈 화면 전용 컴포넌트
│ ├── layout/ # 레이아웃 관련 (Header, BottomNav)
│ └── ui/ # Shadcn UI (Base Components)
├── hooks/ # Custom React Hooks
├── lib/ # 유틸리티 및 설정
│ ├── api/ # Axios Instance & API Clients
│ └── supabase/ # Supabase Client & Middleware Logic
├── store/ # Zustand State Stores
├── types/ # TypeScript Type Definitions (API, Model 등)
├── constants/ # 공통 상수 및 설정
├── __tests__/ # Unit & Integration Tests (Jest)
├── e2e/ # End-to-End Tests (Playwright)
├── stories/ # Storybook Stories
└── public/ # Static Assets & PWA Manifest
pnpm install
.env.example 파일을 .env로 복사하고, 필요한 환경 변수 값을 설정합니다.
cp .env.example .env
pnpm dev
브라우저에서 http://localhost:3000으로 접속해 확인하세요.
pnpm test
@ducanh2912/next-pwa를 통한 서비스 워커 리소스 캐싱env(safe-area-inset-*))framer-motion과 Next.js template.tsx를 결합한 페이지 전환 애니메이션팀원들과 함께 사용할 협업 규칙 및 컨벤션입니다.
Git Flow 전략을 기반으로 운영합니다.
| 브랜치 | 용도 | 직접 Push |
|---|---|---|
main |
배포 가능한 프로덕션 코드 | ❌ 금지 |
develop |
다음 배포를 위한 개발 브랜치 | ❌ 금지 (PR만 가능) |
feat/#이슈번호-기능명 |
기능 개발 | ✅ 가능 |
fix/#이슈번호-버그명 |
버그 수정 | ✅ 가능 |
feat/#12-login-page
feat/#23-main-banner
fix/#15-header-alignment
fix/#34-api-error-handling
1. 이슈(Issue) 생성
↓
2. develop 브랜치 최신화
git pull origin develop
↓
3. 작업 브랜치 생성
git checkout -b feat/#이슈번호-기능명
↓
4. 작업 및 커밋
↓
5. 원격 저장소 푸시
git push origin feat/#이슈번호-기능명
↓
6. PR 생성 (작업 브랜치 → develop)
⚠️ 중요: 자동화 도구(
commitlint,husky)에 의해 커밋 메시지 규칙이 강제됩니다.
type: subject
type은 필수이며 소문자로 작성subject는 대소문자 구분 없이 작성 가능 (API, UI 등 고유명사 사용 가능)type과 subject 사이에 콜론(:)과 공백 한 칸.) 사용 가능 (선택 사항)| Type | 설명 | 예시 |
|---|---|---|
feat |
새로운 기능 추가 | feat: implement login api |
fix |
버그 수정 | fix: resolve db connection issue |
docs |
문서 수정 (README, 주석 등) | docs: update readme installation guide |
style |
코드 포맷팅, 세미콜론 누락 등 (로직 변경 없음) | style: format code with prettier |
refactor |
코드 리팩토링 (기능 변경 없음) | refactor: simplify user validation logic |
test |
테스트 코드 추가/수정 | test: add unit tests for auth service |
chore |
빌드 업무, 패키지 매니저 설정 등 | chore: update dependencies |
perf |
성능 개선 | perf: optimize database queries |
ci |
CI 구성 파일 및 스크립트 변경 | ci: update github actions workflow |
init |
프로젝트 초기 생성 | init: create project structure |
revert |
커밋 되돌리기 | revert: undo previous commit |
✅ DO
❌ DON'T
✅ feat: add user login component
✅ fix: resolve api timeout error
✅ style: format code with prettier
❌ FEAT: add login (type을 대문자로 작성)
❌ feat:add login (공백 없음)
❌ add login (type 누락)
❌ feat: add login, fix header, update styles (여러 작업 혼재)
PR 템플릿이 설정되어 있습니다. 내용을 충실히 작성해주세요.
type: 요약 #이슈번호
예시: feat: 메인 배너 구현 #23
feat, bug 등) 추가Close #이슈번호 작성하여 이슈 자동 닫기 연결| 단계 | 내용 |
|---|---|
| 1차 리뷰 | AI 코드 리뷰(Gemini Code Assist) 필수 진행 |
| 2차 리뷰 | 최소 1명 이상의 팀원 승인(Approve) 필요 |
| 리뷰 포인트 | 코드의 논리적 오류, 컨벤션 준수, 테스트 코드 작성 여부 |
| 병합 방식 | Squash and Merge 권장 (커밋 히스토리 정리) |
@gemini-code-assist를 태그하여 특정 코드에 대해 질문 가능/gemini review - 새로운 리뷰 요청/gemini summary - 변경 사항 요약 요청husky에 의해 자동 검사| 대상 | 규칙 | 예시 |
|---|---|---|
| 컴포넌트 | PascalCase | LoginButton.tsx, UserProfile.tsx |
| 함수/변수 | camelCase | getUserData, isLoggedIn |
| 상수 | UPPER_SNAKE_CASE | API_BASE_URL, MAX_RETRY_COUNT |
| 파일/폴더 | Next.js 규칙 | page.tsx, layout.tsx |
PR 생성 및 푸시 시 자동으로 다음 작업이 실행됩니다:
⚠️ 주의: 테스트를 통과하지 못하면 Merge가 제한됩니다.
Husky와 lint-staged를 통해 커밋 전 자동 검사:
규칙 위반 시 커밋이 중단되므로, 에러 메시지를 확인하여 수정 후 재시도하세요.
1주 단위 스프린트로 개발 및 배포를 진행합니다.
develop 브랜치에 병합develop → main 병합하여 배포월요일 (Sprint Start)
└─ PO가 할당한 백로그 확인 및 작업 시작
↓
월~목 (Development)
└─ feat 브랜치 작업 → develop으로 지속적 병합
↓
금요일 오전 (Code Freeze)
└─ 새로운 기능 병합 중단
└─ QA (테스트 코드 통과 및 수동 점검)
└─ 버그 수정
↓
금요일 오후 (Release)
└─ QA 통과 후 main 브랜치 병합 및 배포
위 일정은 프로젝트 상황에 따라 유연하게 변경될 수 있습니다.
# 브랜치 생성 및 이동
git checkout -b feat/#이슈번호-기능명
# develop 브랜치 최신화
git pull origin develop
# 현재 브랜치를 develop 기준으로 리베이스
git rebase develop
# 커밋 후 푸시
git add .
git commit -m "feat: add login button"
git push origin feat/#이슈번호-기능명
# 브랜치 삭제 (병합 후)
git branch -d feat/#이슈번호-기능명
pnpm lintpnpm formatgit pull origin develop로 최신 코드 받기git add . 후 git commitgit pushnode_modules 삭제 후 재설치: rm -rf node_modules && pnpm install.next 폴더 삭제 후 재빌드: rm -rf .next && pnpm build.env 파일 존재 및 내용 확인